Dynamic Arrays

Dynamic arrays (DYNARRAY) in VectorScript are similar to static arrays, with the notable exception of how they are dimensioned, or sized. While static arrays are explicitly sized when they are declared in the VAR block of your script, the size of a dynamic array is declared during the actual execution of a script. Dynamic arrays can also be resized at any point during script execution to suit your data storage requirements. As with static arrays, dynamic arrays support any valid fundamental data type, as well as the user-defined STRUCTURE type (see Creating Structures for details).

Dynamic arrays can also be specified as one- or two-dimensional. The general syntax for a one-dimensional dynamic array is:

<identifier> : DYNARRAY [] OF <data type>;

Note that, unlike static arrays, dynamic arrays do not include the size (dimension) of the array in the brackets. This size will be defined when your script is executed. The syntax for a two-dimensional dynamic array is very similar:

<identifier> : DYNARRAY [,] OF <data type>;

As with the one-dimensional dynamic array, note that the index dimensions are not specified in the declaration. The comma, however, is needed to indicate that the array will have two dimensions.

To dimension a dynamic array, VectorScript uses the ALLOCATE keyword (along with a reference to the array) to reserve sufficient space in memory for all the data values that will be stored in the array. ALLOCATE can be used to initially dimension the array prior to first use, or it can be used to re-dimension the array should more (or less) storage space be required. For instance, to allocate five storage locations to an array int_values storing INTEGER values, you could use the following call:

ALLOCATE int_values[1..5];

The range specified inside the brackets indicates the number of elements to be created and reserved for storage.

The following example illustrates practical use of a dynamic array within a script:

 

PROCEDURE Example_42;

VAR

i,j,numtxt : INTEGER;

h : HANDLE;

textStore: DYNARRAY[] OF STRING;

BEGIN

numtxt:=Count(((T=Text) & (SEL=TRUE)));

j:=1;

ALLOCATE textStore[1..numtxt];

h:=FSActLayer;

WHILE (h <> NIL) DO BEGIN

IF (GetType(h) = 10) THEN BEGIN

textStore[j]:=GetText(h);

j:=j+1;

END;

h:=NextSObj(h);

END;

ALLOCATE textStore[1..numtxt+2];

TextOrigin(2,2);

CreateText('New text 1');

numtxt:=numtxt+1;

textStore[numtxt]:=GetText(LNewObj);

TextOrigin(2,4);

CreateText('New text 2');

numtxt:=numtxt+1;

textStore[numtxt]:=GetText(LNewObj);

FOR i:=1 TO numtxt DO BEGIN

Message('Array element ',i,' contains ', textStore[i]);

Wait(1);

END;

END;

Run(Example_42);

In the example, a dynamic array is used to store the text of any selected strings that may be found in the selection set. The script begins by declaring the dynamic array, textStore, along with several other variables. In the VAR block declaration, the dynamic array is specified, but no space is allocated at this point for storage.

The body of the script begins with storing the number of selected text objects found within the selection set in the variable numtxt. This value is then used with the ALLOCATE keyword:

ALLOCATE textStore[1..numtxt];

to initialize the amount of storage space in the dynamic array.

Next, the script processes the selected items, and when it encounters a text object, stores the text in an element of the array. Since the text objects within the selection set were counted, textStore is sized to provide sufficient storage within the array for the exact number of text strings that were found.

Once all the objects have been processed, the array can be redimensioned to allocate more or less space as needed. In the example, additional storage space is reserved with another call to ALLOCATE,

ALLOCATE textStore[1..numtxt+2];

and use the newly added storage locations to store the text created by the script. The script concludes by displaying the values currently stored within the textStore array.

Note that the existing data values stored in the array are preserved when the array is re-dimensioned. If an array is redimensioned to a larger size during execution of the script, VectorScript will preserve all the values currently in the array. VectorScript will also attempt to preserve as many data values as possible if an array is redimensioned to a smaller size. In the case of dimensioning to a smaller size, any values contained in locations beyond the newly defined boundaries of the array will be lost.